<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
  <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
  <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
  <link rel="stylesheet" media="print" type="text/css" href="./print.css" />

  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div class="dokuwiki export">

<h1 class="sectionedit1"><a name="clipboard_support" id="clipboard_support">Clipboard Support</a></h1>
<div class="level1">

<p>
Targetted for release in gEDA 1.8.0.
</p>

</div>
<!-- EDIT1 SECTION "Clipboard Support" [1-71] -->
<h3 class="sectionedit2"><a name="introduction" id="introduction">Introduction</a></h3>
<div class="level3">

<p>
Currently, if you &#039;copy&#039; in gschem and &#039;paste&#039; in another program (or a different instance of gschem), nothing useful happens. We should ideally try and use the system clipboard to enable transparent copying and pasting of schematic data between multiple gschem windows as well as other programs.
</p>

<p>
It would be nice to be able to:
</p>
<ol>
<li class="level1"><div class="li"> Copy in gschem, paste in text editor. Should it paste schematic file source code equivalent to copied elements?</div>
</li>
<li class="level1"><div class="li"> Copy in gschem, paste in another instance of gschem. How should it handle differences in component library settings between programs?</div>
</li>
<li class="level1"><div class="li"> Copy in gschem, paste in &lt;program that understands images&gt;. Should paste an image representation of the copied elements.</div>
</li>
</ol>

<p>
Consider the use case of “I want this circuit in my OpenOffice presentation, let&#039;s try the obvious thing to get it there.”
</p>

</div>
<!-- EDIT2 SECTION "Introduction" [72-930] -->
<h3 class="sectionedit3"><a name="the_x_clipboard" id="the_x_clipboard">The X clipboard</a></h3>
<div class="level3">

<p>
The X window system uses the arcane “selection” protocol for copy/paste between X client applications. By taking charge of a “selection”, an application is able to advertise a number of different datatypes, from which another application can request the most appropriate. Two selections are usually available:
</p>
<ol>
<li class="level1"><div class="li"> The PRIMARY selection is customarily used to hold the last piece of text the user selected, and many programs paste its contents on middle-click.</div>
</li>
<li class="level1"><div class="li"> The CLIPBOARD selection is customarily used with an application&#039;s “Copy”, “Cut” and “Paste” actions.</div>
</li>
</ol>

<p>
Many desktop environments (including GNOME and KDE) run a “clipboard daemon”, which copies the CLIPBOARD contents and makes it available even if the original application quits.
</p>

<p>
Due to the primarily non-textual nature of schematic or symbol data, gschem should use the CLIPBOARD on copy/paste, and ignore the SELECTION.
</p>

</div>
<!-- EDIT3 SECTION "The X clipboard" [931-1845] -->
<h3 class="sectionedit4"><a name="the_windows_clipboard" id="the_windows_clipboard">The Windows clipboard</a></h3>
<div class="level3">

<p>
Research needed.
</p>

</div>
<!-- EDIT4 SECTION "The Windows clipboard" [1846-1896] -->
<h3 class="sectionedit5"><a name="gtk_clipboard_api" id="gtk_clipboard_api">GTK clipboard API</a></h3>
<div class="level3">

<p>
The Gimp Toolkit used by gschem&#039;s <acronym title="Graphical User Interface">GUI</acronym> provides APIs for manipulating the X selection (see <a href="https://developer.gnome.org/gtk2/2.24/gtk2-Clipboards.html" class="urlextern" title="https://developer.gnome.org/gtk2/2.24/gtk2-Clipboards.html"  rel="nofollow">the GTK manual</a>). Since gschem already links against GTK, and the GTK clipboard <acronym title="Application Programming Interface">API</acronym> is considerably simpler than using low-level X library calls (as well as being more portable), gschem should make use of it.
</p>

</div>
<!-- EDIT5 SECTION "GTK clipboard API" [1897-2287] -->
<h3 class="sectionedit6"><a name="buffers_in_gschem" id="buffers_in_gschem">Buffers in gschem</a></h3>
<div class="level3">

<p>
gschem currently uses “buffers” to store cut or copied objects for pasting. A buffer is simply a GList of OBJECTs.
</p>

<p>
When a set of selected items is “copied”:
</p>
<ol>
<li class="level1"><div class="li"> Any existing items in the buffer are freed (the GList and OBJECTS destroyed).</div>
</li>
<li class="level1"><div class="li"> The selection is recursively copied to the buffer.</div>
</li>
</ol>

<p>
When a set of selected items is “cut”:
</p>
<ol>
<li class="level1"><div class="li"> The copying procedure is followed.</div>
</li>
<li class="level1"><div class="li"> All of the selected objects are deleted.</div>
</li>
</ol>

<p>
When a set of selected items is “pasted”:
</p>
<ol>
<li class="level1"><div class="li"> All the items in the buffer are copied into the schematic or symbol&#039;s GList, with an appropriate translation applied.</div>
</li>
</ol>

</div>
<!-- EDIT6 SECTION "Buffers in gschem" [2288-2907] -->
<h3 class="sectionedit7"><a name="clipboard_data_types" id="clipboard_data_types">Clipboard data types</a></h3>
<div class="level3">

</div>

<h4><a name="schematic_symbol_data" id="schematic_symbol_data">Schematic/symbol data</a></h4>
<div class="level4">

<p>
<a href="http://git.geda-project.org/geda-gaf/commit/?id=6a07d737a32a816f43e1f061409a10e616d7aa2a" class="urlextern" title="http://git.geda-project.org/geda-gaf/commit/?id=6a07d737a32a816f43e1f061409a10e616d7aa2a"  rel="nofollow"> Implemented in 1.5.2+</a>.
</p>

<p>
On “copy to clipboard”, gschem copies the selected objects to <code>GSCHEM_TOPLEVEL→clipboard_buffer</code>, gets control of the CLIPBOARD selection, and advertises <code>application/x-geda-schematic</code> data. On receiving a request, gschem uses <code>o_save_buffer()</code> to convert the selected objects to gEDA&#039;s on-disk schematic format for transmission.
</p>

<p>
On “paste from clipboard”, gschem looks to see if the current owner of the CLIPBOARD selection is advertising <code>application/x-geda-schematic</code> data. If so, gschem requests the data, and uses <code>o_read_buffer()</code> to convert it to an object list, which it then enters the paste mode for.
</p>

<p>
To simplify the implementation, the first schematic data buffer is currently used as an intermediate store for clipboard data.
</p>

<p>
For the time being, it is assumed destination gschem instance has its library set up correctly – i.e. no changes made to the embedding status of the data being sent before serialisation.
</p>

</div>
<!-- EDIT7 SECTION "Clipboard data types" [2908-] --></div>
</body>
</html>
